Sprite World Functions

DISCUSSION

You call this function to create a new sprite world with associated destination and sprite layer graphics worlds, and either a background color or a background graphics world. Once created, you can manipulate the sprite world and add sprites to it using other sprite toolbox functions. The sprite world created by this function has an identity matrix. The sprite world does not have a clip shape.

The newSpriteWorld , destination , and spriteLayer parameters are all required. You should specify a background color, a background graphics world, or both. You should not pass nil for both parameters. If you specify both a background graphics world and a background color, the sprite world is filled with the background color before the background sprites are drawn. If no background color is specified, black is the default. If you specify a background graphics world, it should have the same dimensions and depth as the graphics world specified by spriteLayer . If you draw to the graphics worlds associated with a sprite world using standard QuickDraw and QuickTime functions, your drawing is erased by the sprite world's background color.

Before calling NewSpriteWorld , you should call LockPixels on the pixel maps of the sprite layer and background graphics worlds. These graphics worlds must remain valid and locked for the lifetime of the sprite world. The sprite world does not own the graphics worlds that are associated with it; it is the caller's responsibility to dispose of the graphics worlds when they are no longer needed.

RESULT CODES

DISCUSSION

You call this function to dispose of a sprite world created by the NewSpriteWorld function. This function also disposes of all of the sprites associated with the sprite world. This function does not dispose of the graphics worlds associated with the sprite world. It is safe to pass nil to this function.

DISCUSSION

You call this function to change the clip shape of a sprite world. You may pass a value of nil for the clipRgn parameter to indicate that there is no longer a clip shape for the sprite world. This means that the whole area is drawn.

The clip shape should be specified in the sprite world's source space, the coordinate system of the sprite layer's graphics world before the sprite world's matrix is applied to it. The specified region is owned by the caller and is not copied by this function.

RESULT CODES

DISCUSSION

You call this function to change the matrix of a sprite world. You may pass a value of nil for the matrix parameter to set the sprite world's matrix to an identity matrix.

Transformations, including translation, scaling, rotation, skewing, and perspective, are all supported in QuickTime 3.

RESULT CODES

DISCUSSION

You call this function to allow a sprite world the opportunity to redraw its invalid areas. This is the only function that causes drawing to occur; you should call it as often as is necessary.

The flagsIn parameter contains flags that describe allowable actions during the idle period. For the default behavior, you should set the value of this parameter to 0. The flagsOut parameter is optional; if you do not need the information returned by this parameter, set the value of this parameter to nil .

Typically, you would make changes in perspective for a number of sprites and then call SpriteWorldIdle to redraw the changed sprites.

RESULT CODES

DISCUSSION

Typically, your application calls this function when the sprite world's destination window receives an update event. Invalidating an area of the sprite world will cause the area to be redrawn the next time that SpriteWorldIdle is called.

The invalid rectangle pointed to by the invalidArea parameter should be specified in the sprite world's source space, the coordinate system of the sprite layer's graphics world before the sprite world's matrix is applied to it. To invalidate the entire sprite world, pass nil for this parameter.

When you modify sprite properties, invalidation takes place automatically; you do not need to call InvalidateSpriteWorld .

RESULT CODES

DISCUSSION

You call this function to determine whether any sprites exist at a specified location in a sprite world's display coordinate system. If you are drawing the sprite world in a window, you should call GlobalToLocal to convert the location to your window's local coordinate system before passing it to SpriteWorldHitTest .

You use the spriteHitTestBounds and spriteHitTestImage flags in the flags parameter to control the hit test operation. Set the spriteHitTestBounds flag to check if there has been a hit anywhere within the sprite's bounding box. Set the spriteHitTestImage flag to check if there has been a hit anywhere within the sprite image.

A hit testing operation does not occur unless you pass one of the flags, either SpriteHitTestBound or SpriteHitTestImage . You can add other flags as needed.

RESULT CODES

DISCUSSION

This function calls the DisposeSprite function for each sprite associated with the sprite world.